home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 5 / Apprentice-Release5.iso / Source Code / Libraries / Sherlock 2.0 / Mac v2.0 docs / Text Docs / Mac Installation .txt < prev    next >
Text File  |  1996-04-05  |  12KB  |  316 lines
  1. Installing Sherlock on the Macintosh
  2.  
  3.  
  4. This chapter provides step-by-step instructions for installing Sherlock.  It also explains in detail 
  5. everything you need to know about initializing Sherlock.
  6.  
  7.  
  8. (Optional) Use the SPP application to insert Sherlock macros in your C files
  9.  
  10. SPP inserts tracing macros to print the values of all arguments to functions and the values returned 
  11. from all functions.  Refer to the SPP Reference for full details.
  12.  
  13.  
  14. Include sl.h in all your source files
  15.  
  16. SPP can do this for you.  Or you can just insert  #include "sl.h"   in your application’s master 
  17. header file.  Also, make sure the compile-time constant called SHERLOCK is defined before  the
  18.  
  19. #include "sl.h".
  20.  
  21.  
  22. Add code to initialize Sherlock.
  23.  
  24. The section below called “How to initialize Sherlock” tells how to do this.
  25.  
  26.  
  27. Add Sherlock Resources to your application.
  28.  
  29. The file SL Resources contains resources used by Sherlock.  Use ResEdit if necessary to change 
  30. the resource ID’s in SL Resources so that they conflict with none of the resources in your 
  31. application.  If you change resource ID’s in SL Resources  you should change the #define 
  32. constants at the beginning of the file mac_gui.c.
  33.  
  34.  
  35. Create a debugging version of your application.
  36.  
  37. Compile and link your source files with Sherlock’s support routines.  The names of all these 
  38. routines are listed in the file called Mac files.  Use ResEdit to add the Sherlock resources in SL 
  39. Resources to your application.  If you forget to add these resources, the Sherlock support routines 
  40. will beep and exit during execution of the w_mac_init routine.
  41.  
  42.  
  43. Run your program and enable tracing statements.
  44.  
  45. Enable Sherlock from a simulated command line.  The routines in LIBcmnd.c allow you to read 
  46. such a command-line easily.  The source code for SPP, SDEL and SDIF provide examples.
  47.  
  48.  
  49.  
  50. Create a production version of your application.
  51.  
  52. After debugging is complete, #undef the SHERLOCK constant and recompile all your source 
  53. files.  All the code produced by the Sherlock macros will disappear.  Relink your program without 
  54. the Sherlock support routines to produce a production version of your program.
  55.  
  56.  
  57.  
  58. How to initialize Sherlock
  59.  
  60. Initialize Sherlock on a Macintosh as follows:
  61.  
  62. {
  63.  
  64.     char ** argv;
  65.  
  66.     int * argc;
  67.  
  68.     w_mac_init(...)
  69.  
  70.     SL_INIT();
  71.  
  72.     init_args(&argc, &argv, lib_arg_file_name);
  73.  
  74.     SL_PARSE(argc, argv, "++", "--");
  75.  
  76.     arg_do_argv(argc, argv); // optional application function
  77.  
  78. }
  79.  
  80.  
  81. Let's look at each line of this code.  First, we declare the argv and argc variables.  Sherlock 
  82. expects to receive arguments from the command line's argv vector.  On the Macintosh the argv 
  83. vector does not exist, so the Macintosh version of Sherlock contains the init_args routine that 
  84. treats a text file as a simulated command line.
  85.  
  86.  
  87. Next, we call w_mac_init.  This routine sets up the Sherlock menus and the log window.  
  88. w_mac_init can also insert other menus into the menu bar.  See below for full details.
  89.  
  90.  
  91. Next we call SL_INIT to initialize the Sherlock support routines.  
  92.  
  93.  
  94. Next we call init_args to read the file specified by lib_arg_file_name.  The template file called 
  95. LIBlib.c contains a dummy definition for several variables, including lib_arg_file_name. Your 
  96. application should create its own version of LIBlib.c, say MyAppLib.c, which contains the name 
  97. of a file to use as the simulated command line.
  98.  
  99.  
  100. init_args reads the text file, parses it into separate arguments, allocates an argv vector, fills in the 
  101. argv vector with pointers to the arguments, and computes the value of argc.  The init_args routine 
  102. takes three arguments: the address of a pointer to the future argv vector, the address of the argc 
  103. value, and the name of the file containing the arguments.
  104.  
  105. The format of the text file processed by init_args is as follows:  Arguments are delimited by white 
  106. space, but strings delimited by matching double quote characters are treated as a single argument.  
  107. An exclamation mark starts a comment that continues to the end of the file.
  108.  
  109.  
  110. Next, we call SL_PARSE to process and remove Sherlock arguments from the argv vector.  The 
  111. "++" and "--" arguments to SL_PARSE above specify that the prefix ++ enables a Sherlock 
  112. argument and the prefix -- disables a Sherlock argument.  For example, the two arguments
  113.  
  114. ++a  --b would enable tracepoint a and disable tracepoint b.
  115.  
  116.  
  117. The function that I have called arg_do_argv is optional.  If your application uses command-line 
  118. arguments, the place to process those arguments is right after the call to SL_PARSE.
  119.  
  120.  
  121.  
  122. The w_mac_init routine
  123.  
  124. w_mac_init routine takes 17 parameters which describe your application.  This routine creates the 
  125. log window used by Sherlock, and can, at your option, install menus.  Finally, it can also initialize 
  126. the Macintosh ToolBox for you.  The following paragraphs discuss each argument in detail.
  127.  
  128.  
  129. w_mac_init    (
  130.  
  131.     Boolean toolBoxFlag,        /* TRUE: Auto Initialize Toolbox. */
  132.  
  133.     Boolean toWindowFlag,        /* TRUE: Send output to window. */
  134.  
  135.     char * windowName,        /* Name of window. */
  136.  
  137.     Boolean openWindowFlag,        /* TRUE: Open window now. */
  138.  
  139.     Boolean addStdMenuFlag,        /* TRUE: Insert File and Edit menus. */
  140.  
  141.     Boolean addSlMenuFlag,        /* TRUE: Insert Sherlock menu. */
  142.  
  143.     Boolean addAboutFlag,        /* TRUE: Add "about" apple menu item. */
  144.  
  145.     char * aboutTitle,        /* Title of "about" apple menu item. */
  146.  
  147.     void (*aboutCallBack) (void),    /* "about" callback routine. */
  148.  
  149.     Boolean menuBarFlag,        /* TRUE: insert added menus now. */
  150.  
  151.     void (*eventCallBack) (void),    /* Event loop callback routine. */
  152.  
  153.     void (*dump1CallBack)(void),    /* First user callback routine. */
  154.  
  155.     pstring userItem1,        /* Menu string for 1st user routine. */
  156.  
  157.     void (*dump2CallBack)(void),    /* Second user callback routine. */
  158.  
  159.     pstring userItem2,        /* Menu string for 2nd user routine. */
  160.  
  161.     void (*dump3CallBack)(void),    /* Third user callback routine. */
  162.  
  163.     pstring userItem3            /* Menu string for 3rd user routine. */
  164.  
  165. );
  166.  
  167.  
  168. toolBoxFlag:  When TRUE, w_mac_init initializes the Macintosh Toolbox as follows:
  169.  
  170.  
  171.     InitGraf( (Ptr) &thePort);
  172.  
  173.     InitFonts();
  174.  
  175.     FlushEvents(everyEvent,0);
  176.  
  177.     InitWindows();
  178.  
  179.     InitMenus();
  180.  
  181.     TEInit();
  182.  
  183.     InitDialogs(0L);
  184.  
  185.     InitCursor();
  186.  
  187.  
  188. Warning:  Your application must not call any of these routines if toolBoxFlag is TRUE.  Sherlock 
  189. will crash if toolBoxFlag is FALSE and the application has not already called these initialization 
  190. routines.  Note that this code does not call MoreMasters or MaxApplZone.
  191.  
  192.  
  193. toWindowFlag:  When TRUE all Sherlock output (the output produced by the Sherlock macros 
  194. themselves as opposed to the output produced inside the macros) is sent to the Sherlock Log 
  195. Window.  Otherwise, Sherlock output is sent to stdout.
  196.  
  197.  
  198. windowName:  A C string (not a Pascal string) containing the name of the Sherlock window.
  199.  
  200.  
  201. openWindowFlag: When TRUE the Sherlock window remains open after being initialized.
  202.  
  203.  
  204. addStdMenuFlag: When TRUE w_mac_init inserts standard Apple, File and Edit menus into 
  205. the application’s menu bar.  The Apple menu contains an optional “about item” followed by the 
  206. usual list desk accessories.  The File menu contains only a Quit item.  The Edit menu contains the 
  207. standard undo, cut, copy, paste and clear items and is highlighted only when a desk accessory is 
  208. chosen from the Apple menu.  When addSlMenuFlag is TRUE, w_mac_init inserts a Sherlock 
  209. menu into the menu bar.  Typically this flag would be set to SHERLOCK_DEFINED so that the 
  210. Sherlock menu will be installed whenever SHERLOCK is #defined.
  211.  
  212.  
  213. addAboutFlag: When TRUE, w_mac_init inserts an “about item” as the first item of the Apple 
  214. menu.  The aboutTitle and aboutCallBack parameters to w_mac_init are meaningful only when 
  215. addAboutFlag is TRUE.
  216.  
  217.  
  218.  
  219. aboutTitle: A C string (not a Pascal string) containing the title of the menu item which is inserted 
  220. as the first item of the Apple menu.  Command key equivalents are valid in this string.  See Inside 
  221. Macintosh page I-346 for details.
  222.  
  223.  
  224. aboutCallBack: The address of a function to be called whenever the “about item” is selected.  
  225. This function must be a void function requiring no arguments.  This function should put up a 
  226. modal dialog giving the current version and possibly other information about the application.
  227.  
  228.  
  229. drawMenuFlag: When TRUE, w_mac_init inserts menus immediately. Otherwise the menus are 
  230. inserted (via hidden entry points) the first time the application calls DrawMenuBar.  
  231.  
  232.  
  233. eventCallBack: The address of a function to be called whenever a line of output is sent to the 
  234. Sherlock window.  To use the minimal event loop defined in the w_applEvent routine, pass the 
  235. address of the following routine as the eventCallBack parameter:
  236.  
  237.  
  238.     void eventCallBack(void)
  239.  
  240.     {
  241.  
  242.         if (w_applEvent(0) == FALSE) {
  243.  
  244.             es("Program terminated by user.\n");
  245.  
  246.             exit(0);
  247.  
  248.         }
  249.  
  250.     }
  251.  
  252.  
  253. dump2CallBack, dump2CallBack and dump3CallBack:  The addresses of function to be 
  254. called when the one of three “user item” in the Sherlock menu is selected.  NULL is valid and 
  255. indicates that the indicated user item does not exist.
  256.  
  257.  
  258. userItem1, userItem1 and userItem1: Pascal strings (not  C strings) containing the titles of 
  259. the user items to be inserted into the Sherlock menu.  Use a null Pascal string, that is, "\p", for 
  260. unused entries.
  261.  
  262.  
  263.  
  264. Adding an Event Loop to your Application
  265.  
  266. w_applEvent contains a minimal event loop.  It handles all events for the Sherlock window and 
  267. menu.  It returns FALSE if the quit item was chosen from the standard File menu.  Applications 
  268. with no event loop should call sl_applEvent periodically and regularly.  The best way to do this is 
  269. to set the eventCallBack parameter to w_mac_init as shown above.
  270.  
  271. w_applEvent can slow down a program noticeably.   skipCount  reduces this time overhead by 
  272. causing sl_applEvent to execute only once every skipCount times that sl_applEvent is called.  
  273. Typically a skipCount of 5 to 20 is appropriate.  Making skipCount too small slows down the 
  274. application.  Making skipCount too large decreases the rate at which events are handled.
  275.  
  276.  
  277. Do not call w_applEvent if your application already has an event loop.  Instead Sherlock will 
  278. update its windows and menus using hidden entry points, defined via macros.  See the next 
  279. section for details.
  280.  
  281.  
  282.  
  283. Hidden entry points
  284.  
  285. The following #define’s appear in sl.h.  They are used if your application does have an event loop.  
  286. In that case, you should not call w_applEvent, nor should you specify an event call back routine in 
  287. the call to w_mac_init.
  288.  
  289.  
  290.     #define GetNextEvent(a,b)      w_event(a,b,0L,((RgnHandle)0),0)
  291.  
  292.     #define WaitNextEvent(a,b,c,d)  w_event(a,b,c,d,1)
  293.  
  294.     #define MenuSelect(a)          w_menuSelect(a)
  295.  
  296.     #define DrawMenuBar          w_drawMenuBar
  297.  
  298.  
  299. These macros form hidden entry points into the routines in mac_gui.c which maintain the Sherlock 
  300. window.  Each corresponding entry in mac_gui.c calls the ToolBox routine with the same name as 
  301. the macro and performs other tasks as described in the next paragraph.
  302.  
  303.  
  304. w_event is the main event loop for the Sherlock code.  This routine calls either the GetNextEvent 
  305. or WaitNextEvent ToolBox routine, depending on the value of the last parameter.  If the returned 
  306. event relates to Sherlock, sl_event handles it and returns FALSE, thereby indicating a NULL 
  307. event.  Otherwise, the event is passed on to the application untouched.
  308.  
  309.  
  310. w_menuSelect calls the MenuSelect ToolBox routine, handles any event in the Sherlock menu 
  311. and returns false, and passes any events for the application’s menus on to the application.
  312.  
  313.  
  314. w_drawMenuBar installs the Sherlock menu in the menu bar and calls the DrawMenuBar 
  315. ToolBox routine.
  316.